.\" sbutils.conf(4)
.\"
.\" Copyright (C) 2002-2005, 2008, 2010 The Written Word, Inc.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2, or (at your option)
.\" any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software Foundation,
.\" Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
.\"
.\" $Id: sbutils.conf.4 708 2010-02-26 22:19:23Z china $
.TH sbutils.conf 4 "2010 February 20"

.SH NAME
sbutils.conf

.SH "FILE FORMAT"
The configuration file, located by default in
``%sysconfdir%/sbutils.conf'', contains defaults used by the \fBsb\fR
program. The file is line-based -- that is, each newline-terminated
line represents either a comment or a parameter. No line-continuation
syntax is available.

Comments begin with a hash, `#'. All text from the hash forward is
ignored.

Variable assignments are of the form 'name = value' (single valued) or
'name = [ value value ... ]' (array valued). Only the first equal sign
is significant. Whitespace before or after the first equal sign is
discarded. Leading and trailing whitespace in a parameter value is
discarded. Variables that take multiple values have their value
bracketed with braces, '[' and ']'. The list below details which
variables take array values (even when assigning one value to a
variable that can take more than one value, the braces are required).
If the value is a string, it should be quoted ('"').

.TP 8
.I bash-path = <path>
Path to bash program. All scripts are run through bash for
cross-platform portability. Bash is invoked with the command-line
arguments ``\fI\-\-noprofile\fR'' and ``\fI\-\-norc\fR'' to limit the
side-effects of system and user-settings.

.TP
.I build-dir = <path>
Path used to unpack source files to.

.TP
.I check-sig = <boolean>
Verify the GPG signature of the package. Equivalent to the
``\fI\-\-check\-sig\fR'' command-line option. Use of the
``\fI\-\-gpg\-keyring\-path\fR'' option or definition of the
``gpg\-keyring\-path'' variable is required with this option.

.TP
.I depots = "'[' <url> <url> ... ']'"
Software depot to search for programs. Equivalent to the
``\fI\-\-depot\fR'' command-line option.

.TP
.I dist = <dist>
Distribution to search for program in. The default CD distribution is
``cd''. For custom builds, ``\fI<dist>\fR'' will be the value
assigned.

.TP
.I dist-ver = "'[' <ver> <ver> ... ']'"
Distribution version. Equivalent to the ``\fI\-\-dist\-ver\fR''
command-line option.

.TP
.I dtd-dirs = "'[' <path> <path> ... ']'"
List of paths to search for DTDs. By default, only ``%datadir%'' is
searched.

.TP
.I egd-socket = <path>
Pathname to the socket the EGD/PRNGD daemons are listening on.
Equivalent to the ``\fI\-\-egd\-socket\fR'' command-line option.

.TP
.I gpg-keyring-path = <path>
Specifies the location of the GPG keyring. The usual location of the
keyring is ~/.gnupg. However, for security reasons, we encourage use
of a dedicated directory for the keyring. This option is required if
``\fI\-\-check\-sig\fR'' is given or if the ``check\-sig'' variable is
defined.

.TP
.I install-base
Installation base directory. Software is expected to be installed in a
directory wholly owned by the software program, ``[install
base]/[install path]''. The installation prefix, combining the
installation base and installation path is available as
``${SB_INSTALL_PREFIX}''.

.TP
.I install-path
Installation path containing the name of the program. Software is
expected to be installed in a directory wholly owned by the software
program, ``[install base]/[install path]''. The installation path can
contain multiple directory components and the variable
``${SB_INSTALL_NAME}'' which is substituted with the value of the
``<install\-name>'' element. The installation prefix, combining the
installation base and installation path is available as
``${SB_INSTALL_PREFIX}''.

.TP
.I lib-path-component = <string>
Library subdirectory to search under dependency prefix for libraries.
When the ``var'' attribute is specified in a ``<depend>'' element, the
``<var>_LIB'' variable is set (where <var> is the value specified by
the ``var'' attribute) if the ``\fIlib\fR'' subdirectory is found
under the dependency prefix. If the ``\fIlib\fR'' subdirectory is not
the correct ``library'' directory to search in for the existence of a
library, then an alternate diretory name must be specified, using this
variable. For example, on x86_64 systems, ``lib64'' might be more
appropriate.

.TP
.I lib-search-path-components = "'[' <ver> <ver> ... ']'"
Like ``lib-path-component'', but provides a list of library
directories to search.

.TP
.I local-depot = <path>
Specifies the location to a remote repository to hold files retrieved
when the depot is remote. Equivalent to the ``\fI\-\-local\-depot\fR''
command-line option.

.TP
.I login = <string>
Login, if required, to remote depot. Equivalent to the
``\fI\-\-login\fR'' command-line option.

.TP
.I password = <string>
Password, if required, to remote depot. Equivalent to the
``\fI\-\-password\fR'' command-line option.

.TP
.I proxy-host = <hostname>
Hostname of proxy server. Equivalent to the ``\fI\-\-proxy\-host\fR''
command-line option.

.TP
.I proxy-login = <string>
Login, if required, on proxy server. Equivalent to the
``\fI\-\-proxy\-login\fR'' command-line option.

.TP
.I proxy-password = <string>
Password, if required, on proxy server. Equivalent to the
``\fI\-\-proxy\-password\fR'' command-line option.

.TP
.I quilt = <boolean>
Interpret patch paths ending with "/" as quilt-style patches.

.TP
.I quilt-patches = "<directory>"
Directory to search under the patch path, if it ends with "/" and
``quilt'' is true. It should match the $QUILT_PATCHES environment
variable or the ``QUILT_PATCHES'' variable in the quiltrc file.

.TP
.I rename-matching-install-prefix-entries = [0|1]
If a program being installed installs to the same installation prefix
as a program that already exists in the installation database, rename
the database entry to the new version.

.TP
.I sftp-known-hosts-path = <string>
Path to ``ssh_known_hosts'' file.

.TP
.I sftp-private-key-path = <string>
Path to ssh private key file.

.TP
.I systype-path = <path>
Path to the GNU config.guess script to determine the architecture
type. The result is available in ${SB_SYSTYPE}.

.TP
.I tmpbasedir = <string>
Temporary base directory to use when creating temporary files. Needed
when package payload too big for default temporary directory (/tmp or
/var/tmp). Equivalent to the ``\fI\-\-tmpbasedir\fR'' command-line
option.

.TP
.I umask = <mask>
Set default umask.

.TP
.I unique-install-prefix = [0|1]
Require \fI\-\-force\fR if some version of program installed with the
same installation prefix.

.TP 
.I verbose = <num>
Increase verbosity of output. A higher value increases the verbosity
level.

.SH "SECTIONS"
The configuration file can contain brace-delimited sections to specify
specific options for a distribution and the default environment. The
``depot'' section identifier is used to specify options specific to a
given depot, the ``dist\-opts'' section identifier is used to specify
options specific to a distribution, and the ``environment'' identifier
is used to specify variables to set in the environment during the
configure, build, and install process.

The ``dist\-opts'' section contains an additional sub-section,
``systype'', to specify platform-specific variables. The ``systype''
variable takes a single argument containing the GNU platform triplet
(e.g. sparc\-sun\-solaris2.9) or a shell wildcard pattern used to
patch the GNU platform triplet (e.g. *\-solaris2.9). It can also be
used outside of the ``dist\-opts'' section to specify global defaults
for all distributions.

Sections are of the form 'section arg { ... }'.

.nf
.RS 4
systype <platform> {
  name = value
}

depot <url> {
  name = value
  name = value
  ...
}

dist-opts <dist> {
  name = value
  name = value
  ...

  systype <platform> {
    name = value
  }
  ...
}

environment {
  var = value
  ...
}
.RE
.fi
.P

Variable assignments made within a depot section refer only to the
``\fI<url>\fR'' the depot is specified for. If a variable is not
assigned to in a depot section, the global value assigned to the
variable in the configuration file is used. By allowing per-depot
variable values, \fBsbutils\fR can retrieve packages from multiple
depots at once and retrieve packages from different directories in all
depots.

Within a depot, the only variables unique to the depot are
``dist\-ver'', ``login'', and ``password''. While all other variables
can be assigned to and will be specific to the depot, they will not be
used.

Variable assignments made within a ``dist\-opts'' section are
applicable to the distribution (``\fI<dist>\fR'') indicated.

Variable assignments made within a ``systype'' section are applicable
to the platform (``\fI<platform>\fR'') indicated.

If a variable is not assigned in a specific section, the global value
is used as the default.

Variables set in the ``environment'' section are available in the
environment for configure, build, test, and install, uninstall, and
purge scripts. An exception is made to the rule in the beginning of
the document allowing the line continuation character '\' (example
below). The only environment made available to build scripts apart
from those specified in the ``environment'' section are ``DISPLAY'',
``EDITOR'', ``HOME'', ``IFS'', ``PATH'', ``TERM'', ``TTY'', and
``TZ''. Variables specified in the ``environment'' section override
existing definitions.

.SH EXAMPLES
Sample configuration file to build software in the ``/opt/build''
directory using an installation prefix of ``/opt/TWWfsw/[package]''.
.nf
.RS 4
build-dir = /opt/build
dist = cd
verbose = 1

environment {
  PATH = "/opt/tww/bin:/usr/ccs/bin:/usr/vac/bin:/bin:/usr/bin:\\
/sbin:/usr/sbin:/etc:/usr/etc:/usr/openwin/bin:/usr/dt/bin:\\
/usr/bin/X11:/opt/imake/bin:/usr/ucb:/usr/bsd"
}

dist-opts cd {
  install-base = "/opt/TWWfsw"
  install-path = "${SB_INSTALL_NAME}"
}
.RE
.fi

.SH FILES
.TP 20
.I %sysconfdir%/sbutils.conf
Configuration file

.TP
.I %sysconfdir%/sbutils.conf.sample
Sample configuration file

.SH "SEE ALSO"
.BR sb (1)

.SH AUTHOR
\fBThe Written Word\fR <info@thewrittenword.com>
